# 构建配置

## builderConfig

- **类型**: `RsbuildConfig`

用于自定义 Rsbuild 的配置项，完整配置项请查看 [Rsbuild - 配置](https://rsbuild.rs/zh/config/)。

- 示例：使用 [resolve.alias](https://rsbuild.rs/zh/config/resolve/alias) 配置路径别名：

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});
```

- 示例：使用 [tools.rspack](https://rsbuild.rs/zh/config/tools/rspack) 修改 Rspack 配置，比如注册一个 webpack 或 Rspack 插件。比如：

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    tools: {
      rspack: async (config) => {
        const { default: ESLintPlugin } = await import('eslint-webpack-plugin');
        config.plugins?.push(new ESLintPlugin());
        return config;
      },
    },
  },
});
```

::: warning

如果你想要修改产物输出目录，请使用 [outDir](/api/config/config-basic#outdir)。

:::

## builderConfig.plugins

- **类型**: `RsbuildPlugin[]`

用于注册 [Rsbuild 插件](https://rsbuild.rs/zh/plugins/list/)。

你可以利用 Rsbuild 丰富的插件生态来增强和扩展构建能力。

- 示例：通过 [@rsbuild/plugin-vue](https://rsbuild.rs/plugins/list/plugin-vue) 支持 Vue SFC。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  builderConfig: {
    plugins: [pluginVue()],
  },
});
```

- 示例：通过 [rsbuild-plugin-google-analytics](https://github.com/rspack-contrib/rsbuild-plugin-google-analytics) 添加 Google analytics。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginGoogleAnalytics({
        // replace this with your Google tag ID
        id: 'G-xxxxxxxxxx',
      }),
    ],
  },
});
```

- 示例：通过 [rsbuild-plugin-open-graph](https://github.com/rspack-contrib/rsbuild-plugin-open-graph) 添加 Open Graph meta 标签。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginOpenGraph({
        title: 'My Website',
        type: 'website',
        // ...options
      }),
    ],
  },
});
```

你也可以覆盖内置的 [@rsbuild/plugin-react](https://rsbuild.rs/zh/plugins/list/plugin-react) 并自定义插件的选项。

比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginReact({
        // ...options
      }),
    ],
  },
});
```

### 默认配置

如果你需要查看默认的 Rspack 或 Rsbuild 配置，可以在执行 `rspress dev` 或 `rspress build` 命令时，添加 `DEBUG=rsbuild` 参数：

```bash
DEBUG=rsbuild rspress dev
```

在执行后，`doc_build` 目录下会生成 `rsbuild.config.js` 文件，里面包含了完整的 `builderConfig`。

> 请查看 [Rsbuild - 调试模式](https://rsbuild.rs/zh/guide/debug/debug-mode) 来了解更多调试 Rsbuild 的方法。

## markdown

配置 MDX 相关的编译能力。

### markdown.remarkPlugins

- **类型**: `Array`
- **默认值**: `[]`

用于增加一些自定义 remark 插件。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import remarkAutolinkHeadings from 'remark-autolink-headings';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [
        remarkAutolinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});
```

### markdown.rehypePlugins

- **类型**: `Array`

用于增加一些自定义的 rehype 插件。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import rehypeAutoLinkHeadings from 'rehype-autolink-headings';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        rehypeAutoLinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});
```

### markdown.shiki

- **类型**: `import('@shikijs/rehype').RehypeShikiOptions`

- **默认值**:

```ts
const cssVariablesTheme = createCssVariablesTheme({
  name: 'css-variables',
  variablePrefix: '--shiki-',
  variableDefaults: {},
  fontStyle: true,
});
const shikiOptions = {
  theme: cssVariablesTheme,
  defaultLanguage: 'txt',
  lazy: true,
  langs: ['tsx', 'ts', 'js'],
  addLanguageClass: true,
};
```

配置 Shiki 相关配置。具体可见 [RehypeShikiOptions](https://github.com/shikijs/shiki/blob/main/packages/rehype/src/types.ts)。

### markdown.link

- **类型**:

```ts
export type RemarkLinkOptions = {
  checkDeadLinks?:
    | boolean
    | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};
```

- **默认值**: `{ checkDeadLinks: true, autoPrefix: true }`

配置链接相关的配置。

#### markdown.link.checkDeadLinks

- **类型**: `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **默认值**: `true`

开启这个配置后，会基于约定式路由对文档中的链接进行检查，若出现无法访问的链接，构建会抛出错误并退出。

如果存在误判链接的情况，可以通过 `excludes` 配置忽略该错误：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: {
        excludes: ['/guide/getting-started', '/llms.txt'],
      },
    },
  },
});
```

#### markdown.link.autoPrefix

- **类型**: `boolean`
- **默认值**: `true`

开启这个配置后，会基于约定式路由对文档中的链接自动增加关于 [国际化](/guide/default-theme/i18n) 和 [多版本](/guide/default-theme/multi-version) 前缀。

比如，用户在 `docs/zh/guide/index.md` 中写了一个链接 `[](/guide/getting-started)`，Rspress 会自动将其转换为 `[](/zh/guide/getting-started)`。

### markdown.showLineNumbers

- **类型**: `boolean`

是否显示代码块的行号。默认为 `false`。

### markdown.defaultWrapCode

- **类型**: `boolean`

是否默认启用长代码换行展示。默认为 `false`。

### markdown.globalComponents

- **类型**: `string[]`

注册全局组件，无需 import 语句，就可以在每个 MDX 文件中使用。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  markdown: {
    globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
  },
});
```

这样你就可以在 MDX 文件中使用 `Alert` 组件了：

```mdx title="test.mdx"
<Alert type="info">This is a info alert</Alert>
```
